I think it could be helpful to make a version of this document for each PartiQL version and implementation listing the reserved keywords (at least the versions with differences).

This can be useful as PartiQL versions change and develop over time. I know we've had similar questions related to our builtin functions (e.g. does partiql-lang-kotlin-x.y.z support this builtin function?).

For reference Microsoft's SQL server has different pages for their different versions:

• SQL-server 2022 -- https://learn.microsoft.com/en-us/sql/t-sql/language-elements/reserved-keywords-transact-sql?view=sql-server-ver16
• SQL-server 2019 -- https://learn.microsoft.com/en-us/sql/t-sql/language-elements/reserved-keywords-transact-sql?view=sql-server-ver15
• ...

I think putting two additional dimensions (i.e., implementation and version) brings too much overhead unless we have a clear spec. definition for this. I see this document's objective to give a general list of possible keywords and a way to escape them while mentioning that the actual keywords can be different.

Perhaps a good compromise is adding PartiQL Spec. Version?

I agree that it could add overhead. I still think we should document somewhere though each implementation + implementation version's reserved keywords since they may change and add more keywords over time. Perhaps for each implementation we can have a doc listing the reserved keywords. As we perform new tagged releases on GitHub, we'll then have a link to the reserved keywords of that specific PartiQL version.

E.g. if we had a document called reserved-keywords.adoc in partiql-lang-kotlin, we could reference it like:

• https://github.com/partiql/partiql-lang-kotlin/tree/vx.y.z-alpha/docs/reserved-keywords.adoc
  And for Rust do something similar:
• https://github.com/partiql/partiql-lang-rust/tree/vx.y.z-alpha/docs/reserved-keywords.adoc

I generally agree, but I think we need to automate this using the Grammar in the code.

Perhaps we could add an issue for each implementation to

• make a reserved keywords doc listing all the reserved keywords
• have some way to automate this doc?
  I think it can still be helpful to have the reserved keywords of each implementation/version visible

Just reflecting the offline response:

I think the following note should be sufficient:

Reserved keywords are yet to be https://github.com/partiql/partiql-spec/issues/2[formally defined] in PartiQL Specification, therefore there may be some differences in different PartiQL implementations.

I’m hesitant to go to a lower level b/c that increases the likelihood of exposing stale information if for example, Rust grammar changes.

I still think we need a story around versioned docs for implementations though and I’m going to open an issue for that.

Will update this thread with the issue.

Here is the issue for tracking the version-based documentation:
#46

I agree that it could add overhead. I still think we should document somewhere though each implementation + implementation version's reserved keywords since they may change and add more keywords over time. Perhaps for each implementation we can have a doc listing the reserved keywords. As we perform new tagged releases on GitHub, we'll then have a link to the reserved keywords of that specific PartiQL version.

E.g. if we had a document called reserved-keywords.adoc in partiql-lang-kotlin, we could reference it like:

• https://github.com/partiql/partiql-lang-kotlin/tree/vx.y.z-alpha/docs/reserved-keywords.adoc
  And for Rust do something similar:
• https://github.com/partiql/partiql-lang-rust/tree/vx.y.z-alpha/docs/reserved-keywords.adoc

"Reserved Keywords" -- no need to capitalize, I'd think (the previous line doesn't).

"cannot be used in PartiQL statements as-is" --> "cannot be used as non-delimited identifiers". That's what a keyword means commonly. "Delimited" rather than "quoted" is the SQL terminology, I believe, but that's secondary.

Style-wise, 4 occurrences of "PartiQL" in 2 lines is a bit much. :-)

Style-wise, 4 occurrences of "PartiQL" in 2 lines is a bit much. :-)
Yep, tbh it was intentional to add some SEO twist to it as this will be in the website :)
Let me see if I can tone it down a bit.

Oh, with SEO in the picture, I wash my hands. :-)